home *** CD-ROM | disk | FTP | other *** search
/ PC Plus SuperCD (UK) 1997 May / PC Plus Super CD Issue 127 (May 1997).iso / handson / handson.exe / PIECRUST.DOC < prev    next >
Encoding:
Text File  |  1997-05-01  |  29.0 KB  |  890 lines
  1.  
  2. PIECRUST ROUTINES AND PARAMETERS                       1/12/96
  3. --------------------------------
  4.  
  5.  
  6. These routines are available within PIECRUST.BAS for QBasic
  7.  
  8.  
  9.  
  10. ziDragging
  11.     This sets the SHARED variable "Response", returning zero if
  12.     the mouse is not being dragged.
  13.  
  14. ziDrawBank( From, To )
  15.     This draws (or redraws) the selected consecutive buttons, using
  16.     specifications within the SHARED array "Bank()".
  17.  
  18.     Each entry within "Bank()" (up to 20)defines the appearance,
  19.     location and state of a button. The TYPE construct "Buttons"
  20.     is used to access each of the features of a button:
  21.       Buttons(i).Xloc   = "X" graphic coordinate of top left corner
  22.       Buttons(i).Yloc   = "Y" graphic coordinate of top left corner
  23.       Buttons(i).Wide   = width in pixels of the button (horizontal)
  24.       Buttons(i).Deep   = depth in pixels of the button (vertical)
  25.         (using HORIZONTAL pixel unit size)
  26.         NOTE: 0 defines a check button (round)
  27.               1 defines a square "sculpted" button
  28.       Buttons(i).State  = 0 for OFF,       i for ON
  29.       Buttons(i).Active = 0 for not used,  1 for used
  30.  
  31.     Using the "Active" component you can vary which buttons are
  32.     displayable, apart from whether they are already defined.
  33.  
  34. ziExhaust
  35.     This sets the SHARED variable "Response" to zero if the mouse
  36.     has not been clicked since last checked.
  37.  
  38. ziLoadFont( Font$ )
  39.     This loads as a font (used by "ziPublish") an OVL file with a
  40.     specified name.  The file can be in the current directory or
  41.     anywhere in the PATH.  Only one font can be loaded at any one
  42.     time. This loads the font via "zzInPath"
  43.  
  44. ziLocateMCursor( X, Y )
  45.     This sets the mouse cursor to the prescribed X and Y coordinates,
  46.     and makes it visible (which renders the mouse "active").
  47.  
  48. ziMouseOnButton( From, To )
  49.     This sets the SHARED variable "FoundButton" to the number of
  50.     a button between "From" and "To", on which the mouse cursor is
  51.     found.  If the mouse cursor is not within the area of a button,
  52.     the value returned is zero.
  53.         The buttons are the active ones in the range which have
  54.     been defined within the SHARED array "Bank()" (up to 20).
  55.  
  56. ziPublish( Phrase$, size, slope )
  57.     This writes to the screen in the loaded font (see "ziLoadFont")
  58.     characters from the string "Phrase$" in the colours specified by the
  59.     SHARED variables "fg" (foreground, or ink) and "bg" (background, or
  60.     paper), and at the location of the graphics cursor (top left corner
  61.     of the first character).  Note that the graphics cursor is then
  62.     advanced.  "Size" governs the size of each character: 1 = 8 x 8
  63.     pixels.  and 2 = 16 x 16 pixels, and so on. (Zero will work as if
  64.     it were size 1).
  65.         "Slope" defines two other characteristics:
  66.             +1 will write an ITALIC character
  67.             +2 will write the foreground of the character only
  68.     (so if "Slope" = 3 the routine will print italic form, foreground
  69.     only).  Setting "foreground only" condition allows you to write
  70.     characters over any background without it checking the colour of
  71.     pixels.
  72.  
  73.     Example:
  74.         LOCATE 10,45
  75.         Call zsAlignGCursor
  76.         Call ziPublish( "This appears at (10,45)", 1, 0)
  77.  
  78.     Note: the graphics cursor is advanced to the next appropriate
  79.     character position following the printed string, but you should
  80.     beware that you leave more space if you decide to follow italicised
  81.     characters with non-italicised characters with two consecutive
  82.     calls to "ziPublish".
  83.  
  84. ziPublishHere( row, column, Phrase$, size, slope)
  85.     This is identical to "ziPublish", except that it takes as input
  86.     the row and column numbers (text notation).  If both are set
  87.     to zero, the current text position will be used. On exit both
  88.     the text and graphic cursors will be set at the position
  89.     following the last character.
  90.  
  91. ziRadio ( Button, From, To )
  92.     This sets the ".State" component of the specified "Button" ON (=1)
  93.     and of all the other buttons in the range between "From" and "To"
  94.     OFF (=0).  In effect this links the buttons in the range like the
  95.     buttons on a pushbutton radio: only one button will be ON at a time.
  96.         This can be used along with "ziMouseOnButton" to simulate
  97.     the operation of "radio" buttons..
  98.  
  99.     Example:
  100.         CALL ziMouseOnButton
  101.         IF FoundButton > 0 THEN
  102.           CALL ziRadio( FoundButton, 1, 20)
  103.         END IF
  104.  
  105.  
  106. ziReadField( Minimum, Maximum, Permitted$ )
  107.     Reads a field at the current text cursor location, with "Maximum"
  108.     as its maximum size and "Minimum" as its minimum number of
  109.     significant characters.
  110.         The "Permitted$" string specifies what kind of characters
  111.     are permitted within the field:
  112.         "*" = any characters
  113.         "." = ensure no more than one full-stop (useful for
  114.             fields intended to be numeric)
  115.         "A" = auto-enter when "Maximum" reached (instead of
  116.             insisting on "Enter" to finish the field)
  117.         "C" = capitalise any letters
  118.         "E" = "Esc" allowed - which sets field empty
  119.         "J" = justify output on the right (especially for numbers)
  120.         "N" = numbers allowed
  121.         "P" = password-type display (you can count characters, but
  122.             they are not recognisable)
  123.         "S" = space allowed
  124.         "X" = alphabetic characters allowed
  125.         "Y" = Y or N allowed regardless of case (useful to get Yes
  126.             or No answers)
  127.     You can use several letters in combination: for example..
  128.  
  129.         CALL ziReadField( 3, 7, "NJ.")
  130.             - obtain a field from input with between 3 and 7
  131.               significant figures, permitting decimal.
  132.  
  133.         CALL ziReadField( 1, 1, "CYA")
  134.             - obtain a single character "Y" or "N" without
  135.               waiting for an Enter key to finish (return
  136.               as a capital letter)
  137.  
  138.     The result is returned in the SHARED variable "Field$"
  139.  
  140. ziSetMCursorVis( Status )
  141.     This routine sets the visibility status of the Mouse cursor:
  142.         0 = set the mouse cursor OFF
  143.         1 = set the mouse cursor ON
  144.         2 = request the current status of the mouse cursor
  145.            10 = set the mouse cursor OFF temporarily
  146.            11 = restore the previous status of the mouse cursor
  147.     Many screen-drawing functions are diverted by the mouse cursor if
  148.     it is visible, so you should take care to turn it off temporarily
  149.     while changing the screen, using "Status" set to 10, and then
  150.     restore it (if it were on) using "Status" set to 11.  Those
  151.     PIECRUST routines that alter the screen do this automatically.
  152.  
  153.     The resulting status is returned in any case is returned in the
  154.     SHARED variable "MCursorVis", with 0 = invisible and 1 = visible.
  155.  
  156. ziWander( Timeout! )
  157.     This routine returns mouse or keyboard events in the SHARED
  158.     variable "Response" as follows..
  159.  
  160.     &H100    -Enter key
  161.     &H101    -left arrow
  162.     &H102    -right arrow
  163.     &H103    -up arrow
  164.     &H104    -down arrow
  165.     &H105    -backspace
  166.     &H106    -Home
  167.     &H107    -End
  168.     &H108    -Page up
  169.     &H109    -Page down
  170.     &H10A    -Tab
  171.     &H10B    -Escape
  172.  
  173.     If the Ctrl key is held down, this adds &H100 to these
  174.     values (except Ctrl/up arrow, Ctrl/down arrow and Ctrl/Tab, which
  175.     do not return any value).
  176.  
  177.     &H40A is returned for shift/Tab
  178.  
  179.     Function keys are returned in the following way:
  180.  
  181.     &H10nn    -Function key "nn" (00 to 09, 0A, 0B, 0C)
  182.     &H20nn  -Function key "nn" with Ctrl held down
  183.     &H40nn  -Function key "nn" with shift held down
  184.  
  185.     In addition the following mouse events are detected:
  186.  
  187.     &H800    -double-click
  188.     &H801    -left click
  189.     &H802    -right click
  190.     &H803    -both click
  191.     &H804    -left click and drag
  192.     &H805    -right click and drag
  193.     &H806    -both click and drag
  194.  
  195.     Note that double-click (&H800) will not be reported unless the
  196.     SHARED variable "DClick" is set to 1; this slows down
  197.     event-checking, and may not be desirable. "DClick" is initially
  198.     set to OFF.
  199.  
  200.     Note that two other SHARED variables are returned: "HResponse" and
  201.     "LResponse".  If, for example, "Response" is &H208
  202.     (Ctrl/Page down), "HResponse" (H for HIGH) is set to &H2, while
  203.     "LResponse" is set to &H8.
  204.  
  205.     The SHARED string variable "Allowed$" contains any other characters
  206.     you wish to detect with ziWander: if a character that appears within
  207.     this string is keyed, "HResponse" will be set to zero, and..
  208.  
  209.         MID$(Allowed$, Response)
  210.  
  211.     ..will indicate which character was keyed.
  212.  
  213.     The "Timout!" parameter indicates a timeout (in seconds) to terminate
  214.     this routine. If the routine is terminated by such a timeout, the
  215.     "Response" passed back is zero. If you do not wish a timeout, pass
  216.     the value zero in the parameter.
  217.  
  218. zsAlignGCursor
  219.     This routine aligns the graphic cursor (which is determined by pixel
  220.     displacements) with the current location of the text cursor.
  221.     Example:
  222.         LOCATE 10,22
  223.         CALL zsAlignGCursor
  224.     This is particularly handy for determining where to place graphic
  225.     images (which includes 8x8 font characters via "ziPublish"), LINE
  226.     or DRAW graphics, and even setting the location of the mouse cursor
  227.     by following this with "CALL ziLocateMCursor( GXloc, GYloc )".
  228.  
  229. zsAlignTCursor
  230.     This routine does the reverse of zsAlignGCursor, setting the text
  231.     cursor to the character position containing the current pixel
  232.     indicated by the graphics cursor.
  233.  
  234. zsLocateGCursor( xcoordinate, ycoordinate )
  235.     This routine places the graphics cursor at a particular point.  This
  236.     in effect does what the "LOCATE" command accomplishes for the text
  237.     cursor.
  238.  
  239. zsPastel( xcoord, ycoord, wide, deep, colour1, colour2 )
  240.     This creates an oblong (rectangle) starting at the named graphic
  241.     point, creating a pastel mixture of the two colours.
  242.     Note that if you create a background with this function you should,
  243.     when using the "ziPublish" routine, use the "+2" from of the "slope"
  244.     paramater so that the background is left as is, and only the
  245.     positive part of each character overwrites the background.
  246.  
  247. zsSetScrnMode( mode, highrows, highcolumns)
  248.     This sets the screen with the colours indicated in the SHARED
  249.     parameters "bg" and "fg".  The mode parameter must be 9 or 12, and
  250.     each of the other parameters should be 0 or 1: they indicate the
  251.     number of rows and columns for which the screen will be configured:
  252.     The number of rows and columns available obtained are as follows..
  253.  
  254.     mode  highrows=0  highrows=1  highcols=0  highcols=1
  255.  
  256.       9     25          43          40          80
  257.      12      30          60          40          80
  258.      13      25          25          40          40
  259.  
  260.     This routine also sets values into the SHARED variables Xmax and
  261.     Ymax (giving the number of the rightmost X coordinate and the
  262.     bottommost Y coordinate); also the SHARED value XYratio! is
  263.     calculated and set.  This aids in the determination of distances
  264.     on the screen; since the X and Y increments are not the same,
  265.     XYratio! will help you find the equivalence.
  266.  
  267. zsSubstitute( xcoord, ycoord, wide, deep, colour1, colour2)
  268.     This routine substitutes each pixel of colour1 with colour2 within
  269.     a defined oblong (rectangle) starting at the named graphic point.
  270.     This is useful for changing either the foreground or the background
  271.     (for example) without disturbing other pixels.
  272.  
  273. zzAlphaSort( Sortdata$() )
  274.     The routine sorts the items in the specified STRING ARRAY; note that
  275.     the parameter MUST be a string array.  The SHARED variable
  276.     "SortCount" indicates how many items in the array will be sorted.
  277.     Note that the "0" entry of the array is used as a work area, and
  278.     should be ignored.
  279.  
  280. zzBasicInt( interrupt )
  281.     This routine executes a system interrupt, using registers as
  282.     defined and set in the SHARED "Regs" construct.  The only parameter
  283.     is an integer specifying the interrupt number: &H10 (or 16) for BIOS
  284.     and &H21 (or 33) for DOS are by far the most commonly used.
  285.     Many interrupts return new information in the registers, and
  286.     indicate success or failure of their task with the setting of the
  287.     "carry" flag.  The state of the "carry" flag can be determined by
  288.     the following expression..
  289.  
  290.         (Regs.FL AND 256)
  291.  
  292.     ..which will be 0 if not set, or 256 if it is set.
  293.  
  294.     On first execution this routine calls "zzInPath" to load the
  295.     machine code stored in "BASICINT.OVL".
  296.  
  297. zzChangeDir( directory$ )
  298.     This routine makes the directory specified in the string the
  299.     current directory associated with the drive on which it is found.
  300.     If the directory or drive is invalid or nonexistent, there is no
  301.     change and the directory$ string is replaced with a single
  302.     question mark ("?").  If the change is successful the full directory
  303.     path is placed in the string, even if only a partial or "shortcut"
  304.     path was specified.
  305.  
  306.     If the directory$ string is empty, or has only a drive specification,
  307.     there is no change to the "current directory" status.  Instead, the
  308.     path of the current directory associated with the specified (or
  309.     default) drive is placed in the string.
  310.  
  311.     If you have two logical drives sharing a full physical unit (as A:
  312.     and B: do when there is no physical second floppy drive) and you
  313.     select a directory from the non-active logical drive letter, this
  314.     routine will automatically substitute the active logical drive
  315.     letter, and you will not get a "change drive" message.
  316.  
  317. zzChangeDrive( drive$ )
  318.     This routine makes the drive specified in the string the current
  319.     drive. If the drive is invalid or nonexistent, there is no
  320.     change and the drive$ string is replaced with a single question
  321.     mark ("?").  If the change is successful the drive letter
  322.     (followed by a colon ":") is placed in the string.
  323.  
  324.     If the drive$ string is empty, there is no change to the "current
  325.     drive" status.  Instead, the letter (plus a colon ":") of the
  326.     current drive is placed in the string.
  327.  
  328.     If you have two logical drives sharing a full physical unit (as A:
  329.     and B: do when there is no physical second floppy drive) and you
  330.     select the non-active logical drive letter, this routine will
  331.     automatically substitute the active logical drive letter,
  332.     and you will not get a "change drive" message.
  333.  
  334. zzFileSelectBox( pattern$ )
  335.     This routine operates a full-screen File Select Box, based on the
  336.     path and/or pattern passed as a string parameter. It offers the
  337.     ability to browse around all available drives on the system, and
  338.     from them select a file that matches the pattern.  If no pattern is
  339.     supplied, all files will be shown on the screen.
  340.  
  341.     This routine utilises several other routines, and makes use of the
  342.     SHARED arrays "FileNames$()" and "Directories$()" and their associated
  343.     counts, "FileNames" and "Directories".  The string used to pass the
  344.     pattern to the routine will, on exit, contain the selected file's
  345.     full path (including drive), or "?" if the dialog was aborted without
  346.     a selection (usually by "Esc" key).
  347.  
  348. zzInPath( filename$ )
  349.     This routine verifies whether the specified file is in the
  350.     current directory, or otherwise within a directory in the PATH.
  351.     If it is, it substitutes the string with the full path to the file.
  352.     If it is not, it sets the string to null (zero length).
  353.  
  354. zzSearchD( pattern$ )
  355.     This pattern searches a specified directory for a particular pattern
  356.     of subdirectory names; if no path is named, the current path is
  357.     assumed.  If no pattern is named, "*.*" (which means "any name") will
  358.     be assumed.
  359.  
  360.     The results will be placed in the SHARED array "Directories$()", and
  361.     the number of such resulting matches will be placed in the SHARED
  362.     variable "Directories".  Note that the results in the array will be
  363.     sorted into alphabetic sequence.
  364.  
  365.     If the pattern is incorrectly formatted, or if it contains an invalid
  366.     or nonexistent path, it will be replaced by "?".  Otherwise the
  367.     full path, including the drive, will be added to the beginning
  368.     of the "wildcard" part of the pattern string.
  369.     replaced by the full path, including the drive letter.
  370.  
  371. zzSearchF( pattern$ )
  372.     This pattern searches a specified directory for a particular pattern
  373.     of file names; if no path is named, the current path is    assumed.  If
  374.     no pattern is named, "*.*" (which means "any name") will be assumed.
  375.  
  376.     The results will be placed in the SHARED array "FileNames$()", and the
  377.     number of such resulting matches will be placed in the SHARED variable
  378.     "FileNames".  Note that the results in the array will be sorted into
  379.     alphabetic sequence.
  380.  
  381.     If the pattern is incorrectly formatted, or if it contains an invalid
  382.     or nonexistent path, it will be replaced by "?".  Otherwise the
  383.     full path, including the drive, will be added to the beginning
  384.     of the "wildcard" part of the pattern string.
  385.  
  386.  
  387. zzValidate( path$ )
  388.     This routine will validate that the drive and path specified is
  389.     correctly formatted, and exists.  The full drive and path will be
  390.     returned if it is valid, and "?" will be returned if it is not.
  391.  
  392.  
  393. PIECRUST SHARED VARIABLES
  394. -------------------------
  395.  
  396. Allowed$    - string of other allowed keystrokes (passed back directly)
  397.         during the running of "ziWander".
  398.  
  399. Bad
  400.         - transferred value of trapped ERR
  401.  
  402. Bank()        - integer array for describing Buttons, as used by
  403.         various routines (ziDrawBank, ziMouseOnButton, ziRadio)
  404.         It is described by the "Buttons" TYPE construct.  See the
  405.         desciption of routine "ziDrawBank".
  406.  
  407. bg        - background colour
  408.  
  409. Col        - current column number (after zsAlignGCursor and
  410.         zsAlignTCursor)
  411.  
  412. Cols        - number of columns in text mode: set by "ziSetScrnMode"
  413.         and used by the "zsAlign" cursor routines.
  414.  
  415. Dclick          - set to tell whether double-clicks are to be specific
  416.         events captured by "ziWander" (whcih can slow down
  417.         general operation).  0 = no detection,  1 = detection
  418.  
  419. Directories    - integer count of entries within "Directories$"
  420.  
  421. Directories$()    - string array of directories found by zzSearchD
  422.  
  423. fg         - foreground colour
  424.  
  425. Field$        - response area for the ziReadField routine
  426.  
  427. FileNames    - integer count of entries within "FileNames$""
  428.  
  429. FileNames$()    - string array of filenames found by zzSearchF
  430.  
  431. Font()          - two-dimensional integer array containing loaded font
  432.         information related to ziLoadFont and ziPublish.
  433.  
  434. FoundButton    - number of button on which the mouse cursor has clicked
  435.         (see ziMouseOnButton routine)
  436.  
  437. GXloc        - X (horizontal) component of the location of the graphics
  438.         cursor
  439.  
  440. GYloc        - Y (vertical) component of the location of the graphics
  441.         cursor
  442.  
  443. HResponse    - the isolated high portion of "Response"
  444.  
  445. LResponse    - the isolated low portion of "Response"
  446.  
  447.  
  448. MCursorVis    - visibility flag for mouse cursor; 0 = invisible, 1= visible
  449.  
  450. Module$        - name of module to load via "ziLoadFont"
  451.  
  452. MXloc
  453.             - X (horizontal) component of the location of the mouse
  454.         cursor
  455.  
  456. MYloc        - Y (vertical) component of the location of the mouse cursor
  457.  
  458. Response    - integer response to "ziWander" routine, indicating mouse
  459.         and keyboard events
  460.  
  461. Row         - current row number (after zsAlignGCursor and
  462.         zsAlignTCursor)
  463.  
  464. Rows        - number of rows in text mode: set by "ziSetScrnMode" and
  465.         used by the "zsAlign" cursor routines.
  466.  
  467. SortCount    - integer count of the number of items input to "zzAlphaSort"
  468.  
  469. Xmax        - maximum pixel number for X (horizontal), set by
  470.         zsSetScrnMode
  471.  
  472. XYRatio!    - ration between size of X and Y pixel increments, set by
  473.         zsSetScrnMode
  474.  
  475. Ymax         - maximum pixel number for Y (vertical), set by
  476.         zsSetScrnMode
  477.  
  478.  
  479. Note also the SHARED variables for registers, used in zzBasicInt:
  480.  
  481.     Regs.AX,  Regs.BX,  Regs.CX,  Regs.DX,
  482.     Regs.DS,  Regs.SI,  Regs.ES,  Regs.DI,
  483.     Regs.FL
  484.  
  485. These are used for interfacing to DOS and BIOS interrupts.
  486.  
  487.  
  488.  
  489.  
  490. PIECRUST CONSTANTS
  491. ------------------
  492.  
  493. DegToRad! = .0174533    (the multiplication factor to convert degrees
  494.              to radians)
  495.  
  496. Ex! = 2.71828        (e - the exponential constant)
  497.  
  498. Pi! = 3.14159        (pi)
  499.  
  500. RadToDeg! = 57.2958    (the multiplication factor to convert radians
  501.              to degrees)
  502.  
  503. NOTE: the following all apply to the interpretation of the results
  504.       from "ziWander"
  505.  
  506. ziBoth = 3        (match with LResponse to determine "both buttons")
  507.  
  508. ziBothDrag = 6        (match with LResponse to determine "both drag")
  509.  
  510. ziBS = 5        (match with LResponse to determine "backspace")
  511.  
  512. ziCTRL = &H2        (match with HResponse to determine Ctrl shift)
  513.  
  514. ziCTRLFn = &H20        (match with HResponse to determine Ctrl/Function)
  515.  
  516. ziDbl = 0        (match with LResponse to determine "double-click")
  517.  
  518. ziDn = 4        (match with LResponse to determine "down")
  519.  
  520. ziEnd = 7        (match with LResponse to determine "end")
  521.  
  522. ziEsc = 11        (match with LResponse to determine "escape")
  523.  
  524. ziFn = &H10        (match with HResponse to determine Function key)
  525.  
  526. ziHome = 6        (match with LResponse to determine "home")
  527.  
  528. ziL = 1            (match with LResponse to determine "left")
  529.  
  530. ziLDrag = 4        (match with LResponse to determine "left drag")
  531.  
  532. ziMouse = &H8        (match with HResponse to determine a mouse event)
  533.  
  534. ziNoShift = &H1        (match with HResponse to determine no shift)
  535.  
  536. ziPgDn = 9        (match with LResponse to determine "page down")
  537.  
  538. ziPgUp = 8        (match with LResponse to determine "page up")
  539.  
  540. ziR = 2            (match with LResponse to determine "right")
  541.  
  542. ziRDrag = 5        (match with LResponse to determine "right drag")
  543.  
  544. ziShiftFn = &H40    (match with HResponse to determine Shift/Function)
  545.  
  546. ziTab = 10        (match with LResponse to determine "tab")
  547.  
  548. ziUp = 3        (match with LResponse to determine "up")
  549.  
  550.  
  551. OTHER NOTES ABOUT PIECRUST OPERATION
  552. ------------------------------------
  553.  
  554.     Two modules with the extension "OVL" are required as Piecrust is
  555.     normally presented: one facilitates a font for the "ziPublish"
  556.     routine, and the other furnishes the code for the "zzBasicInt"
  557.     routine.  These are called "ASCII8X8.OVL" and "BASICINT.OVL".
  558.     They must be present, but not necessarily in the current
  559.     directory: they may be in any directory in the PATH.
  560.  
  561.  
  562.     Piecrust starts by seeding the random-number generator and testing
  563.     for the presence of a mouse.  This itself activates the "zzBasicInt"
  564.     routine, loading its "OVL" module.
  565.  
  566.     If there is a mouse present the local variable "Mouse" is set to 1,
  567.     but the mouse is NOT activated.  If you want the mouse activated,
  568.     execute the command:   CALL ziSetMCursorVis( 1 )
  569.                    -------------------------
  570.  
  571.     Piecrust then loads the ASCII 8 x 8 font (from an "OVL").
  572.  
  573.  
  574.     There is a special error trap within Piecrust code needed when
  575.     a specified "OVL" module cannot be found.  This is left in place
  576.     and active for the convenience of the programmer, though you
  577.     may turn it off if you desire by executing "ON ERROR GOTO".  The
  578.     installed trap will pass back control normally, but set the SHARED
  579.     variable "Bad" to the value of ERR when the error occurred (which
  580.     itself is lost).  After sensitive instructions - or after
  581.     arithmetic instructions that are susceptible to overflow - you may
  582.     wish to inspect and reset "Bad".
  583.  
  584.  
  585. SUB Function Crossreference Table for PIECRUST
  586. ----------------------------------------------
  587.  
  588. SUB        Called by..           Calls..
  589. ---             -----------             -------
  590.  
  591. base                    ziLoadFont
  592.                     ziSetMCursorVis
  593.                     zzBasicInt
  594.  
  595. ziDrawBank    ziRadio                  ziSetMCursorVis
  596.  
  597. ziDragging                ziExhaust
  598.                     zzBasicInt
  599.  
  600. ziExhaust    ziDragging              zzBasicInt
  601.         ziWander
  602.  
  603. ziLoadFont    base            zzInPath
  604.  
  605. ziLocateMCursor                ziSetMCursorVis
  606.                     zzBasicInt
  607.  
  608. ziPublish    ziPublishHere            ziSetMCursorVis
  609.                     zsLocateGCursor
  610.  
  611. ziPublishHere    zzFileSelectBox            ziPublish
  612.                     zsAlignGCursor
  613.                     zsAlignTCursor
  614.  
  615. ziRadio                    ziDrawBank
  616.  
  617. ziReadField                ziSetMCursorVis
  618.  
  619. ziSetMCursorVis    base                 zzBasicInt
  620.         ziDrawBank
  621.         ziLocateMCursor
  622.         ziPublish
  623.         ziReadField
  624.         zsPastel
  625.         zsSetScrnMode
  626.         zsSubstitute
  627.  
  628. ziWander                ziExhaust
  629.                     zzBasicInt
  630.  
  631. zsAlignGCursor    zsAlignTCursor           zsLocateGCursor
  632.         zzFileSelectBox
  633.  
  634. zsAlignTCursor                zsAlignGCursor
  635.  
  636. zsLocateGCursor    ziPublish
  637.         zsAlignGCursor
  638.  
  639. zsPastel                ziSetMCursorVis
  640.  
  641. zsSetScrnMode    zzFileSelectBox            ziSetMCursorVis
  642.  
  643. zsSubstitute                ziSetMCursorVis
  644.  
  645. zzAlphaSort    zzSearchD
  646.         zzSearchF
  647.  
  648. zzBasicInt    base                    zzInPath
  649.         ziDragging
  650.         ziExhaust
  651.         ziLocateMCursor
  652.         ziSetMCursorVis
  653.         ziWander
  654.         zzChangeDir
  655.         zzChangeDrive
  656.         zzCritOff
  657.         zzCritOn
  658.         zzFileSelectBox
  659.         zzSearchD
  660.         zzSearchF
  661.         zzValidate
  662.  
  663. zzChangeDir    zzFileSelectBox         zzBasicInt
  664.         zzValidate
  665.  
  666. zzChangeDrive    zzValidate               zzBasicInt
  667.                     zzCritOff
  668.                     zzCritOn
  669.  
  670. zzCritOff    zzChangeDrive           zzBasicInt
  671.         zzFileSelectBox
  672.         zzSearchD
  673.         zzSearchF
  674.         zzValidate
  675.  
  676. zzCritOn    zzChangeDrive        zzBasicInt
  677.         zzFileSelectBox
  678.         zzSearchD
  679.         zzSearchF
  680.         zzValidate
  681.  
  682. zzFIleSelectBox               ziPublish
  683.                     zsAlignGCursor
  684.                     zsSetScrnMode
  685.                     zzBasicInt
  686.                     zzChangeDir
  687.                     zzCritOff
  688.                     zzCritOn
  689.                     zzSearchD
  690.                     zzSearchF
  691.                     zzValidate
  692.  
  693. zzInPath    ziLoadFont
  694.         zzBasicInt
  695.  
  696. zzSearchD    zzFileSelectBox          zzAlphaSort
  697.                     zzBasicInt
  698.                     zzCritOff
  699.                     zzCritOn
  700.                     zzValidate
  701.  
  702. zzSearchF    zzFileSelectBox        zzAlphaSort
  703.                     zzBasicInt
  704.                     zzCritOff
  705.                     zzCritOn
  706.                     zzValidate
  707.  
  708. zzValidate    zzFileSelectBox            zzBasicInt
  709.         zzSearchD                 zzChangeDir
  710.         zzSearchF               zzChangeDrive
  711.                     zzCritOff
  712.                     zzCritOn
  713.  
  714.  
  715. Digest of BIOS and DOS INTERRUPTS used within "PIECRUST"
  716. --------------------------------------------------------
  717.  
  718.    Int    Function
  719.    ---    --------
  720.  
  721.  
  722.    21      0Exx    Set current drive
  723.         input:    AX 0Exx
  724.             DX xxNN where NN=drive-1 (A=0, B=1 etc)
  725.         output: AX xxNN where NN=LASTDRIVE value
  726.  
  727.         <used by zzChangeDrive>
  728.  
  729.    21      19xx    Get current drive
  730.         input:    AX 19xx
  731.         output:    AX xxNN where NN=drive-1 (A=0, B=1 etc)
  732.  
  733.         <used by zzChangeDir, zzChangeDrive>
  734.  
  735.  
  736.    21      1Cxx    Get drive data
  737.         input:     AX 1Cxx
  738.             DX xxNN where NN=drive (A=1, B=2, etc)
  739.                    or 00 (current drive)
  740.         output:    AX xxNN where NN=sectors/cluster,
  741.                    or FF if invalid
  742.             BX ptr to Media Descriptor
  743.             CX bytes/sector
  744.             DX clusters
  745.             DS seg to Media Descriptor
  746.  
  747.         <used by zzChangeDrive, zzFileSelectBox, zzSearchD,
  748.           zzSearchF, zzValidate>
  749.  
  750.    21      25xx    Set interrupt vector
  751.         input:     AX 25NN where NN=interrupt to be revectored
  752.             DX ptr to new interrupt handler routine
  753.             DS seg to new interrupt handler routine
  754.  
  755.         <used by zzCritOff, zzCritOn>
  756.  
  757.    21      2Fxx    Get DTA (Disk Transfer Address)
  758.         input:    AX 2Fxx
  759.         output:    BX ptr to DTA
  760.             ES seg to DTA
  761.  
  762.               <used by zzFileSelectBox, zzSearchD, zzSearchF,
  763.           zzValidate>
  764.  
  765.    21      35xx    Get interrupt vector
  766.         input:    AX 35NN where NN=interrupt wanted
  767.         output:    BX ptr to current interrupt handler routine
  768.             ES seg to current interrupt handler routine
  769.  
  770.         <used by base module>
  771.  
  772.    21      3B00    Change current directory
  773.         input:    AX 3Bxx
  774.             DX ptr to ASCIIZ string of new directory name
  775.             DS seg to ASCIIZ string of new directory name
  776.  
  777.         <used by zzChangeDir>
  778.  
  779.    21      440E    Get logical drive map entry
  780.         input:    AX 440E
  781.             BX xxNN where NN=drive number (A=1, B=2, etc)
  782.                    or NN=0 (current drive)
  783.         output:
  784.             if carry flag=0
  785.                 AX xxNN where NN = 0 if device unshared
  786.                            or NN = current logical
  787.             if carry flag=1
  788.                 AX error code
  789.  
  790.         For example if BX=1 on input but 2 was returned in AX,
  791.           then the drive exists, but is currently being called
  792.           "B:" rather than "A:"
  793.  
  794.         <used by zzChangeDrive, zzFileSelectBox,
  795.           zzSearchD, zzSearchF, zzValidate>
  796.  
  797.    21      47xx     Get current directory
  798.         input:  AX 47xx
  799.                 DX xxNN where NN=drive number (A=1, B=2, etc)
  800.                         or NN=0 (current drive)
  801.                 SI ptr to 64-byte buffer
  802.                 DS seg to 64-byte buffer
  803.         output:
  804.                 if carry flag=0
  805.                     buffer contains ASZIIZ path (no base "\")
  806.             if carry flag=1
  807.                 AX error code
  808.  
  809.         <used by zzChangeDir, zzValidate>
  810.  
  811.    21      4Exx    Find first match
  812.         input:    AX 4Exx
  813.             CX 00NN where NN=additional attributes
  814.                       01=readonly
  815.                       02=hidden
  816.                       04=system
  817.                       08=volume ID
  818.                       10=directory
  819.                (this is "additive": eg 07 will count
  820.                 readonly, hidden and system files as
  821.                 candidates)
  822.             DX ptr to ASCIIZ string containing pattern
  823.             DS seg to ASCIIZ stromg containing pattern
  824.         output:    AX error code if carry set
  825.             DTA contains results if carry not set
  826.  
  827.         Note: the following information is in the DTA
  828.             disp    length
  829.             &H15    BYTE    Attributes of matched element
  830.             &H16    INTEGER TIME as HHHHHMMM MMMSSSSS
  831.                    where SSSSS is HALF the seconds
  832.             &H18    INTEGER DATE as YYYYYYYM MMMDDDDD
  833.                   where YYYYYYY is added to 1980
  834.             &H1A    LONG     Size of file
  835.             &H1E    STRING    ASCIIZ string (up to 13 long)
  836.                      containing the element name
  837.  
  838.               <used by zzSearchD, zzSearchF, zzValidate>
  839.  
  840.    21      4Fxx    Find next match (following function 4E repeatedly)
  841.         input:    AX 4Fxx
  842.             DTA must be left as output by preceding 4E
  843.         output: as for 4E
  844.  
  845.               <used by zzSearchD, zzSearchF>
  846.  
  847.    33    0000    Reset mouse and provide status
  848.         input:  AX 0000
  849.         output: AX status (0=no mouse)
  850.             BX number of buttons
  851.  
  852.         <used by base module>
  853.  
  854.    33    0001       Show mouse cursor
  855.         input:    AX 0001
  856.  
  857.         <used by zzSetMCursorVis>
  858.  
  859.    33    0002    Hide mouse cursor
  860.         input:  AX 0002
  861.  
  862.         <used by zzSetMCursorVis>
  863.  
  864.    33    0003    Get mouse cursor position and button status
  865.         input:  AX 0003
  866.         output:    BX status (0=no button down; 1=left down;
  867.               2=right down; 3=both down)
  868.             CX horizontal position
  869.             DX vertical position
  870.  
  871.         <used by ziDragging, ziExhaust, ziWander>
  872.  
  873.    33    0004       Set mouse cursor position
  874.         input:    AX 0004
  875.             CX = horizontal position
  876.             DX = vertical position
  877.  
  878.         <used by ziLocateMCursor>
  879.  
  880.    33    002A     Get mouse cursor hotspot
  881.         input:    AX 002A
  882.         output:    BX cursor hotspot column
  883.             CX cursor hotspot row
  884.             DX mouse type (0=none; 1=bus; 2=serial;
  885.               3=InPort; 4=IBM; 5=HP)
  886.  
  887.         <used by ziSetMCursorVis>
  888.  
  889.  
  890.